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Introduction 
The features of the Roku™ HD1000 can be controlled externally (“scripted”) via a protocol 
called the External Control Protocol (ECP). 


HD1000 users and third-party developers can use the ECP to control HD1000 applications (and 
other applications implementing the Roku ECP APIs). This document covers the basics of using 
the ECP. The appendices in this document contain a complex sample script and a complete 
listing of the ECP commands supported by the HD1000’s built-in applications. For purposes of 
this document, the image viewer will be used as the primary example. 


Roku wants your feedback! 


The ECP commands are provided to make life easier for third parties. If you have suggestions 
for enhancements or additions to ECP support on the HD1000 (or if you find an error in this 
document), please don’t hesitate to write to us at support @rokulabs.com. Requests will be 
considered for inclusion in later software releases. 


ECP basics 


ECP commands are issued from the shell by way of a helper program called (appropriately) 
“ecp.” There are three basic ways to issue these commands: 

1. The commands may be grouped together in a standard Linux shell script. This is the 
most convenient way to issue a sequence of commands that you may want to repeat 
multiple times. Shell scripts may be stored on any media source accessible to the 
HD1000, including the built-in storage, a flash card, or a shared folder on a networked 
computer. 

2. The commands may be issued at the command prompt, via the serial port. Connecting 
a computer to the HD1000’s serial port with a standard serial cable gives you a Linux 
command shell, at which ECP commands may be entered. (The port is 9600bps, 8-N-1, 
no flow control.) 

3. If the HD1000 is on a network, the commands may be issued at the command prompt, 
via a telnet connection. Simply use a telnet program on a networked computer to 
connect as “guest” with no password. The IP address of the HD1000 can be found at 
the top of the screen in the Setup feature. 


Note: In order for an ECP command to be successfully processed, the program that handles 
the command must first be running. For example, in order for the command ‘photoApp’ to be 
processed, the program “photo” must be running. 


Additionally, third-party developers may also issue ECP commands directly from within 


their applications via the Cascadelnput::DispatchECPCommand API. See the developer 
documentation for more information. 


Roku External Control Protocol forthe HD1000 1 


© 2003 Roku, LLC 


ECP command syntax 
The syntax for ecp is as follows: 


ecp <app identifier> <command> [optional arguments] 
For example: 


ecp photoApp IMAGEDIR “/tmp/Volumes/CompactFlash” 
ecp photoApp DISPLAYIMAGE ‘“/tmp/Volumes/CompactFlash/myphoto.jpg” 
ecp photoApp QUIT 


About Paths 


The various media sources available to the HD1000 appear in /mnt where flashO is the built- 
in storage, flash1 is Compact Flash, flash2 is SD/MMC, flash3 is Memory Stick and flash4 is 
SmartMedia. Mounted network shares can be found in /mnt/smb/. 


For your convenience, all currently- mounted media sources can be found with better names 
in /tmp/Volumes . For readability, this is how media sources these scripts below will refer to 
media sources, with a few exceptions. 


Script File Formats 


Scripts are simply text files. However, the format of the files is slightly different than that to 
which most Windows users may be used. Scripts must be saved with unix-style line endings. If 
you use Linux to edit your script files, the format will be correct. However, if you use Windows 
or MacOS to edit your script files, the format of the files may be incorrect, resulting in the 
HD1000 being unable to execute the files. There are text-editors available for Windows that 
are able to save text files with Unix-style line endings. Among these is “TextPad”. There is a 
command-line utility called “dos2unix” that will convert files from Windows line endings to 
Unix line endings. 


An example ECP script 


The following brief example script is a trivial playlist, using the faceless music player to provide 
background music for a four-image slideshow. A longer, more complex example appears in 
the Appendix of this document, and is available for download from the Roku web site. 


#!/bin/sh 

# Launch the Photo app in "playlist" mode. 

# Be sure to launch in background (with &), or the 
# script will not continue past this line! 


photo -p & 


# Wait a bit to make sure Photo has launched. 
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sleep 2 


# Launch the music player (also in the background) 
# --obeyphoto means that it will quit when Photo does 
mp3player --obeyphoto "/tmp/Volumes/CompactFlash/"*.mp3 & 


# Play the images I like 
# Using quotes around the path is a good habit, 
# because paths with spaces must have quotes. 


ecp photoApp IMAGEDIR "/tmp/Volumes/CompactFlash" 

ecp photoApp DISPLAYIMAGE "/tmp/Volumes/CompactFlash/Imagel.jpg" 
sleep 9 

ecp photoApp DISPLAYIMAGE "/tmp/Volumes/CompactFlash/Image3.jpg" 
sleep 9 

ecp photoApp DISPLAYIMAGE "/tmp/Volumes/CompactFlash/Image5.jpg" 
sleep 9 

ecp photoApp DISPLAYIMAGE "/tmp/Volumes/CompactFlash/Image9.jpg" 
sleep 9 


# All done. Quit Photo (which will tell the 
# music player to quit). 
ecp photoApp QUIT 


ECP status feedback 


Applications provide feedback on command success or failure via text status messages. 


$ ecp photoApp IMAGEDIR "/tmp/Volumes/CompactFlash" 
photoApp: invalid path 

$ ecp photoApp IMAGEDIR "/tmp/Volumes/CompactFlash" 
photoApp: ok 

$ ecp fakecommand 

fakecommand: unknown ecp command 


In the case of the last command, the result “unknown ecp command” indicates one of the 
following: 


These status messages can be useful when initially authoring and testing a script. Scripts can 


+ The program that handles the specified command is not running. In the case of 


photoApp, it means that “photo” is not running. 


* The command was mis-typed. Check your spelling 
* The command is an invalid command. 


also check the status messages of commands that may fail to be sure that they should continue 


to run: 


#!/bin/sh 
# Adding /usr/local/bin to the path allows the script 


# to call “photo” and “ecp” instead of 
# “/usr/local/bin/photo” and “/usr/local/bin/ecp” 
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PATH=S$PATH:/usr/local/bin 


Launch the Photo app in "playlist" mode (which opens 
no windows and just waits for ECP commands). 

Be sure to launch in background (with &), or the 
script will not continue past this line! 


+ + H+ H+ 


photo -p & 


# Wait a bit to make sure Photo has launched. 
sleep 2 


# Set the image directory, making sure it’s valid. 
ecp photoApp IMAGEDIR "/tmp/Volumes/CompactFlash" | \ 
grep 'photoApp: ok'! 


# This line tests whether grep returned 0 (meaning 
# that the reply string contained "photoApp: ok") 
if [ $? -eq 0 ] 


then 
ecp photoApp SLIDESHOW "/tmp/Volumes/CompactFlash" 
else 
echo "failed to set directory" 
ecp photoApp QUIT 
fi 


Consult a reference on Linux shell scripting for details on the syntax of shell scripts. 


Running a script from the Main Menu 

It’s easy to make a Script you've written appear in the main menu. Just name your script file 
with a “roku” extension, like “MySlideshow.roku”. Put the file onto a flash card or in the shared 
folder on your computer that you connect to from your HD1000. You will see a button in the 
“Roku Applications” section of the Main Menu corresponding to your new script. 


Note: The file must be marked executable. On most flash cards and file servers, this is 
automatic. Consult your favorite Linux reference for details if you're not certain. 
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Appendix A: A longer script example 


#!/bin/sh 


This script shows a set of images from the Memory 
Stick and SD/MMC cards, while playing music from the 
Compact Flash. It shows off some of the image viewer’s 
features, like pan and zoom and information display. 


HHH H+ 


# Adding /usr/local/bin to the path allows the script 
# to call “photo” and “ecp” instead of 

# “/usr/local/bin/photo” and “/usr/local/bin/ecp” 
PATH=SPATH:/usr/local/bin 


echo "launching" 


# Launch the image viewer, and give it a couple of 

# seconds to start up. We re-direct any output from 
# Photo to /dev/null so as not to clutter up the 

# terminal. You would normally do this with each of 
# the ECP lines as well, but it has been omitted for 
# readability. 

photo -p > /dev/null 2>&1 & 

sleep 2 


# Set the image directory. Photo requires a valid 
# directory to be set in case the user starts 
# punching buttons on the remote. 
ecp photoApp IMAGEDIR “/tmp/Volumes/Memory Stick” | \ 
grep “photoApp: ok” 
if [ $? -ne 0 ] 
echo “setting the image directory failed” 
exit 1 
fi 


# display the first image 
ecp photoApp DISPLAYIMAGE “/mnt/flash3/racecar.jpg" 


# For this slideshow, we won’t display any info. If 
# it was on be default, dismiss it immediately 
ecp photoApp SHOWINFO none 


# Start the music 
mp3player “/tmp/Volumes/CompactFlash/”*.mp3 > /dev/null 2>&1 & 


# Start Photo fetching the next image in the background, 
# so displaying it will be quick 
ecp photoApp PREFETCHIMAGE “/mnt/flash3/Fl1léhires.jpg” 


Turn off info display for all images (we 

do this here because the first command besides the 
directory causes Photo to open the image display 
window, which paints the screen black - waiting until 
the first image has been displayed eliminates the 


+#H HH H+ 
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# black screen). 


ecp 


ph 


# Set 


ecp 


ph 


otoApp INFOMODE none 


the image fit mode to smart 
otoApp FITMODE smart 


# Go ahead and display the image we've started fetching 


ecp 


ph 


otoApp DISPLAYIMAGE "/mnt/flash3/Fléhires.jpg" 


# Start the next image fetching, then wait 7 seconds 
# before displaying it 

ecp photoApp PREFETCHIMAGE "/mnt/flash3/F1i5hires.jpg" 
ecp photoApp DISPLAYIMAGE "/mnt/flash3/F1l5hires.jpg" 


# Next image - start it fetching 
ecp photoApp PREFETCHIMAGE "/mnt/flash3/F22.jpg" 


# After the F-15 has been up for five seconds, show off 
# Photo's zoom and pan features 
sleep 5 


ecp 
ecp 
ecp 
ecp 
ecp 
ecp 
ecp 


otoApp ZOOMIN 
otoApp ZOOMIN 


otoApp ZOOMIN 


otoApp ZOOMIN 


otoApp ZOOMIN 


otoApp ZOOMIN 
otoApp ZOOMIN 


# pan to the left 
sleep 2 


ecp 
ecp 
ecp 
ecp 
ecp 
ecp 
ecp 
ecp 


ph 
ph 
ph 
ph 
ph 
ph 
ph 


otoApp PANLEFT 
otoApp PANLEFT 
otoApp PANLEFT 
otoApp PANLEFT 
otoApp PANLEFT 
otoApp PANLEFT 
otoApp PANLEFT 
otoApp PANLEFT 


to the right 

otoApp PANRIGHT 
otoApp PANRIGHT 
otoApp PANRIGHT 
otoApp PANRIGHT 
otoApp PANRIGHT 
otoApp PANRIGHT 
otoApp PANRIGHT 
otoApp PANRIGHT 
otoApp PANRIGHT 
otoApp PANRIGHT 
otoApp PANRIGHT 
otoApp PANRIGHT 
otoApp PANRIGHT 
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# zoom back out 

ecp photoApp ZOOMOUT 
ecp photoApp ZOOMOUT 
ecp photoApp ZOOMOUT 
ecp photoApp ZOOMOUT 
ecp photoApp ZOOMOUT 
ecp photoApp ZOOMOUT 
ecp photoApp ZOOMOUT 
ecp photoApp ZOOMOUT 
ecp photoApp ZOOMOUT 
ecp photoApp ZOOMOUT 
sleep 5 


# display the pre-fetched image 
ecp photoApp DISPLAYIMAGE "/mnt/flash3/F22.jpg" 
sleep 3 


# show off Photo's info display modes 
ecp photoApp SHOWINFO short 

sleep 2 

ecp photoApp SHOWINFO long 

sleep 6 

ecp photoApp SHOWINFO none 

sleep 1 


# Okay, enough picture-by-picture manual control. Time 
# to let Photo do the work. Start a slideshow with all 
# the images on the SD/MMC card. 

ecp photoApp SLIDESHOW "/mnt/flash2" 

ecp photoApp FITMODE smart 

ecp photoApp INFOMODE none 


# Let the slideshow run for a minute and a half, and 
# then we're done. 

sleep 90 

ecp photoApp QUIT 

ecp mp3player QUIT 

sleep 2 

echo "done" 
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Appendix B: Image Viewer (“Photo”) ECP commands 


The image viewer appication (“Photo”) supports a number of ECP commands. Some are 
simple commands, and others take arguments. 


Photo will accept ECP commands at any time. However, if you wish to manually “drive” the 
application from ECP commands entirely, you may launch Photo with the -p command-line 
switch. This puts Photo into “playlist” mode, where it does not open any initial windows, start 
any threaded decoding or display any images: 


$ photo -p & 


In the present implementation, some ECP commands are not really appropriate in all modes, 
and some may produce unwanted results. 


Specifically, you can think of the app as having two “modes” - a slideshow mode and a 
completely manual mode. (This is not strictly accurate, but it’s the easiest way to explain the 
behavior. The application is actually modeless, but there is state and some of the commands 
modify state while some do not.) 


In the slideshow mode, ECP commands which duplicate the functionality of the remote’s 
buttons are available (zoom, pan, next, prev, play, pause, info) and work as expected. 
Slideshow mode is entered by issuing the SLIDESHOW command. 


In the completely manual mode, the ECP program sending the commands is responsible 

for sending the commands to pre-fetch images and display them (although straight display 
commands do work, they’re slower). In this mode, many of the “normal” features work as 
expected (zoom, pan, info). However, because Photo was designed to work with a list of files 
in a directory, some commands produce unusual results. Specifically, the NEXT_IMAGE and 
PREV_IMAGE commands are relative to the current index in the directory initially set with 
IMAGEDIR. The DISPLAY_IMAGE and PREFETCH_IMAGE commands do not update the position 
in this list, even if the files in question are in the list. Also ROTATE_IMAGE will rotate the image 
which is at the current list index - almost certainly not the image currently displayed. The 
tables that follow break the ECP commands down into commands which work for slideshow, 
commands that work in manual mode, and commands that are valid in both. 


The completely manual mode is the default mode when Photo is launched with -p. It can 
also be entered at any time during a slideshow by simply issuing a PAUSE command and then 
issuing PREFETCH_IMAGE or DISPLAY_IMAGE commands. 


Note that Photo’s normal button and infrared handling is always active. If your application 


desires to completely control Photo while locking out keys, it should open an always-on-top 
window and SetFocus() on that window after launching Photo. This window should trap all keys. 
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Command 


Arguments 


Description 


IMAGEDIR 


<full paths 


Sets the working 
image directory. 
This must be 

set before any 
commands other 
than SLIDESHOW are 
valid. 


SLIDESHOW 


<full paths 


Launch a slideshow 
on the specified 
path. Settings 
from preferences 
are used. 


ROTATE IMAGE 


<none> 


Exactly like 
pressing the rotate 
key on the remote 


ZOOM_IN 


<none> 


Exactly like 
pressing the Zoom 
In key on the 
remote 


ZOOM OUT 


<none> 


Exactly like 
pressing the Zoom 
Out key on the 
remote 


PAN LEFT 


<none> 


Exactly like 
pressing the left 
arrow on the remote 


PAN RIGHT 


<none> 


Exactly like 
pressing the right 
arrow on the remote 


PAN UP 


<none> 


Exactly like 
pressing the up 
arrow on the remote 


PAN DOWN 


<none> 


Exactly like 
pressing the down 
arrow on the remote 
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SET ZOOM AND PAN 


Takes three 
arguments: zoom, 

X pan and Y pan. 
They must be given 
IN THAT ORDER if 
they are provided, 
but all three 

are not required. 
Command should look 


like “SET _ZOOM_AND_ 


PAN zoom=0.5 panxX=- 
75 panYy=85”. Note 
no spaces between 
label and argument, 
with a single space 
between arguments. 


Sets the absolute 
pan and zoom for 
the current image. 
The X pan values 
are constrained 

to values valid 
for the hardware 
scaler. Pan 
coordinates are 
given in terms 

of the original 
decoded image, and 
refer to the center 
point. Thus, the 
pan coordinates 
given at left pan 
the image so that 
its center is 

75 source pixels 
left of the screen 
center and 85 
source pixels down 
from the screen 
center. Zoom is 

a floating-point 
number that can 

be thought of 

as magnification 
(1.0 is “actual 


size”, 2.0 is 
“double size”). 
Again, these 


are constrained 

to valid values 
for the hardware 
scaler. 
[Limitation: if the 
image is too large 
to fit into the 
hardware scaler, 

it is scaled to fit. 
In this case, all 
of the parameters 
listed here are 
scaled as well.] 


Roku External Control Protocol for the HD1000 


10 


© 2003 Roku, LLC 


SHOW_INFO “short”, “long” or | Display the info 
“none” for this image (or 
dismiss if “none” 
specified) 
INFO MODE “short”, “long” or |Set the info mode 
“none” for each subsequent 
image 
FIT MODE “ot, Sali” -or Set the fit mode 
“smart” for each subsequent 
image 
SET DELAY A number in Sets the inter- 
milliseconds. image delay fora 
Numbers less than slideshow 
15 are invalid. 
QUIT <none> Quit the app 


Table B2: Commands valid in Slideshow mode 


Command Arguments Description 

PAUSE <none> Pause a slideshow. 
Not a toggle. 

PLAY <none> Resume/start a 
slideshow. Nota 
toggle. 

NEXT IMAGE <none> Exactly like 
pressing the >>| 
key on the remote 

PREV_IMAGE <none> Exactly like 


pressing the |<< 
key on the remote 
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Table B3: Commands valid in manual mode 


Command Arguments Description 


PREFETCH IMAGE <full path> Launches a 
background thread 
to decode the 
specified image. 
Follow this command 
with DISPLAY IMAGE 
several seconds 


later. 
DISPLAY IMAGE <full path> Fetch and display 

an image. If you 
-or- call PREFETCH IMAGE 

first and allow time 
zoom=<value> for the fetch to 
panX=<value> panY = | complete, then this 
<value> command executes 
«full paths immediately. 

Status return 
(Spaces between blocks until the 
each label/value image has actually 
pair, no spaces displayed. 


allowed between 
label, equals sign, | If the optional 

and value). zoom and pan 
arguments are 
supplied, the image 
is displayed zoomed 
and panned. See 
SET ZOOM AND PAN 
above. 
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Appendix C: Music player (“Listen”) ECP commands 


There are two music playing applications on the HD1000, release 1.0. The first is called “Listen”, 
and it is the GUI player you normally launch from the Main Menu. The second is called 
“mp3player”, and is a faceless background application used by Art Packs or other tasks where 
music is meant to accompany some other display. 


The table below shows commands valid for the Listen app. From the shell, the syntax to invoke 
these commands is: 


ecp ListenApp <command> [<arguments>] 


Unlike Photo, the command is not case-sensitive. 


Table C1: Commands for Listen 


QUIT <none> Stops music 
playback and quits 
the application 


NEXT <none> Advances to 

the next track. 
Equivalent to the 
>>| button on the 
remote 


PREVIOUS <none> If less than 

4 seconds have 
elapsed in the 
current track, 
plays the previous 
track. Otherwise, 
starts the current 
track over from the 
beginning. 


PLAY <none> If paused, resumes 
playback of the 
current track. If 
not playing or 
paused, plays the 
track highlighted 
in the GUI. 


PAUSE <none> Pauses the current 
track. 
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PlaybackPosition 


<none> 


Returns a string 
indicating how 
many seconds have 
elapsed in the 
currently playing 
track. 


CurrentFile 


<none> 


Returns the filename 
of the currently 
playing track. 


CurrentTitle 


<none> 


Prints out the 
ID3-title of the 
currently playing 
track. 


CurrentAlbum 


<none> 


Prints out the 
ID3-album of the 
currently playing 
track. 


CurrentArtist 


<none> 


Prints out the 
ID3-artist of the 
currently playing 
track. 


Current Year 


<none> 


Prints out the 
ID3-year of the 
currently playing 
track. 


SetDirectory 


<full paths 


Set the currently 
viewable-browseable 
directory to 

“full path>, if it 
exists. 


FilePlay 


<filename> 


Plays <filename> 
if it is in the 
currently viewed 
list of files. 
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Appendix D: Background music player (“mp3player”) 

ECP commands 

The next table (below) shows commands valid for the mp3player app. From the shell, the 
syntax to invoke these commands is: 


ecp mp3player <command> [<arguments>] 


Like Listen, the command is not case-sensitive. 


Note: The mp3player application, having no GUI, takes as an argument when it is launched one 
or more .mp3 files to play. These files are placed in an internal list. If playback reaches the end 
of the list, it will start again from the beginning. There are ECP commands for manipulating 
the list. 


Table D1: Commands for mp3player 


QUIT <none> Stops music 
playback and quits 
the application. 


RESUME <none> If paused, resume 
playback. 
PAUSE <none> f playing, pause 
layback 


n the list. 


lays the previous 
file. 

APPEND <full path> Appends the music 
file at <full paths 
to the end of the 
list of files to be 
played. 

INSERT <full paths Inserts the music 
file at <full path> 
after the currently 
playing file in the 
list. 


I 
p 
NEXT <none> Play the next file 
i 
P 


PREVIOUS <none> 
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Appendix E: System ECP Commands 


The table below listen commands that affect the HD1000 as a whole. From the shell, the syntax 
to invoke these commands is: 


ecp system <commands> [<arguments>] 


The command is not case-sensitive. 


Table E1: Commands for the system 


POWER “ON” , “STANDBY” or | Sets the power-on state 
“QUERY” of the system. A argument 
of “On” turns the system 
on. “Standby” puts 
the system into standby 
mode. “Query” returns 


whether the unit is on or 
in standby. If the unit 
is already in the state 
requested, the command 
will have no effect. 


VIDEOMODE A valid combination | If the pair of settings 


of one of (connector and output 
[composite, svideo, mode) is valid, sets 
component, rgb] and | the output to that 
[480i, 480p, 720p, mode, otherwise returns 
768p, 1080i] an error. “RESET” is a 


special case that sets the 
unit into initial video 
settings mode. 


SENDKEY Any of: MENU, Simulates a remote 
POWER, EXIT, NORTH, control keypress of the 
SOUTH, EAST, WEST, corresponding button. 


SELECT, PREVIOUS, 
NEXT, PLAYPAUSE, 
ROTATE, INFO, 
ZOOM_IN, ZOOM OUT 


VERSION <none> Prints out the firmware 
version 
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